.TH "Datastore operations" 3 "Fri Apr 15 2016" "Version 0.10.0-146_trunk" "libnetconf" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Datastore operations \- 
.PP
libnetconf's functions for handling NETCONF datastores\&. More information can be found at \fBDatastores Usage\fP page\&.  

.SS "Modules"

.in +1c
.ti -1c
.RI "\fBFile Datastore\fP"
.br
.RI "\fISpecific functions for NCDS_FILE_DS type of datastore implementation\&. \fP"
.ti -1c
.RI "\fBCustom Datastore\fP"
.br
.RI "\fIlibnetconf's API to use a server-specific datastore implementation\&. \fP"
.in -1c
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBNCDS_INTERNAL_ID\fP   0"
.br
.RI "\fIDatastore ID to access libnetconf's internal datastores such as notifications, monitoring, etc\&. \fP"
.ti -1c
.RI "#define \fBNCDS_RPC_NOT_APPLICABLE\fP   ((void*)(&\fBerror_area\fP))"
.br
.RI "\fIReturn value of \fBncds_apply_rpc2all()\fP when the requested operation is not applicable to the datastore\&. \fP"
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef int \fBncds_id\fP"
.br
.RI "\fIDatastore ID\&. \fP"
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBNC_DATASTORE\fP { \fBNC_DATASTORE_ERROR\fP, \fBNC_DATASTORE_CONFIG\fP, \fBNC_DATASTORE_URL\fP, \fBNC_DATASTORE_RUNNING\fP, \fBNC_DATASTORE_STARTUP\fP, \fBNC_DATASTORE_CANDIDATE\fP }"
.br
.RI "\fIEnumeration of the supported types of datastores defined by NETCONF\&. \fP"
.ti -1c
.RI "enum \fBNCDS_TYPE\fP { \fBNCDS_TYPE_ERROR\fP = -1, \fBNCDS_TYPE_EMPTY\fP, \fBNCDS_TYPE_FILE\fP, \fBNCDS_TYPE_CUSTOM\fP }"
.br
.RI "\fIDatastore implementation types provided by libnetconf\&. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBncds_add_model\fP (const char *path)"
.br
.RI "\fIAdd an configuration data model to the internal list of models\&. Such model is used to resolve imports, includes and uses statements in base models\&. \fP"
.ti -1c
.RI "int \fBncds_add_models_path\fP (const char *path)"
.br
.RI "\fISpecify a directory path to the location where the required (imported or included) data models can be found\&. This function can be called repeatedly to specify multiple locations\&. \fP"
.ti -1c
.RI "\fBnc_reply\fP * \fBncds_apply_rpc2all\fP (struct nc_session *session, const \fBnc_rpc\fP *rpc, \fBncds_id\fP *ids[])"
.br
.RI "\fIPerform the requested RPC operation on the all datastores controlled by the libnetconf (created by ncdsd_new() and \fBncds_init()\fP)\&. \fP"
.ti -1c
.RI "void \fBncds_break_locks\fP (const struct nc_session *session)"
.br
.RI "\fIRemove all the locks that the given session is holding\&. \fP"
.ti -1c
.RI "int \fBncds_consolidate\fP (void)"
.br
.RI "\fIConsolidate all internal structures of created data stores and all data models\&. This function especially solves all YANG's \fCuses\fP and \fCaugment\fP statements\&. \fP"
.ti -1c
.RI "int \fBncds_feature_disable\fP (const char *module, const char *feature)"
.br
.RI "\fIDisable usage of the specified feature defined in the specified module By default, all features are disabled\&. \fP"
.ti -1c
.RI "int \fBncds_feature_enable\fP (const char *module, const char *feature)"
.br
.RI "\fIEnable usage of the specified feature defined in the specified module\&. By default, all features are disabled\&. \fP"
.ti -1c
.RI "int \fBncds_feature_isenabled\fP (const char *module, const char *feature)"
.br
.RI "\fICheck if the feature of the specified module is currently enabled or disabled\&. \fP"
.ti -1c
.RI "int \fBncds_features_disableall\fP (const char *module)"
.br
.RI "\fIDisable usage of all features defined in the specified module\&. By default, all features are disabled\&. To disable only the specific feature(s), use \fBncds_feature_disable()\fP\&. \fP"
.ti -1c
.RI "int \fBncds_features_enableall\fP (const char *module)"
.br
.RI "\fIEnable usage of all features defined in the specified module\&. By default, all features are disabled\&. To enable only the specific feature(s), use \fBncds_feature_enable()\fP\&. \fP"
.ti -1c
.RI "void \fBncds_free\fP (struct ncds_ds *datastore)"
.br
.RI "\fIClose the specified datastore and free all the resources\&. \fP"
.ti -1c
.RI "void \fBncds_free2\fP (\fBncds_id\fP datastore_id)"
.br
.RI "\fIClose specified datastore and free all the resources\&. \fP"
.ti -1c
.RI "char * \fBncds_get_model\fP (\fBncds_id\fP id, int base)"
.br
.RI "\fIReturn a serialized XML containing the data model in the YIN format\&. \fP"
.ti -1c
.RI "const char * \fBncds_get_model_path\fP (\fBncds_id\fP id)"
.br
.RI "\fIReturn path to the file containing the datastore datamodel\&. \fP"
.ti -1c
.RI "\fBncds_id\fP \fBncds_init\fP (struct ncds_ds *datastore)"
.br
.RI "\fIActivate datastore structure for use\&. \fP"
.ti -1c
.RI "int \fBncds_model_info\fP (const char *path, char **name, char **version, char **ns, char **prefix, char ***rpcs, char ***notifs)"
.br
.RI "\fIInformational function to get basic information about configuration data model in the given file\&. \fP"
.ti -1c
.RI "struct ncds_ds * \fBncds_new\fP (\fBNCDS_TYPE\fP type, const char *model_path, char *(*get_state)(const char *model, const char *running, struct nc_err **e))"
.br
.RI "\fICreate a new datastore structure of the specified implementation type\&. \fP"
.ti -1c
.RI "struct ncds_ds * \fBncds_new2\fP (\fBNCDS_TYPE\fP type, const char *model_path, xmlDocPtr(*get_state)(const xmlDocPtr model, const xmlDocPtr running, struct nc_err **e))"
.br
.RI "\fICreate a new datastore structure of the specified implementation type with get_state function using libxml2\&. \fP"
.ti -1c
.RI "int \fBncds_rollback\fP (\fBncds_id\fP id)"
.br
.RI "\fIUndo the last change performed on the specified datastore\&. \fP"
.ti -1c
.RI "int \fBncds_set_validation\fP (struct ncds_ds *ds, int enable, const char *relaxng, const char *schematron)"
.br
.RI "\fISet validators (or disable validation) on the specified datastore\&. \fP"
.ti -1c
.RI "int \fBncds_set_validation2\fP (struct ncds_ds *ds, int enable, const char *relaxng, const char *schematron, int(*valid_func)(const xmlDocPtr config, struct nc_err **err))"
.br
.RI "\fISet validators (or disable validation) on the specified datastore\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
libnetconf's functions for handling NETCONF datastores\&. More information can be found at \fBDatastores Usage\fP page\&. 

libnetconf's functions for handling NETCONF datastores\&.
.SH "Macro Definition Documentation"
.PP 
.SS "#define NCDS_INTERNAL_ID   0"

.PP
Datastore ID to access libnetconf's internal datastores such as notifications, monitoring, etc\&. 
.SS "#define NCDS_RPC_NOT_APPLICABLE   ((void*)(&\fBerror_area\fP))"

.PP
Return value of \fBncds_apply_rpc2all()\fP when the requested operation is not applicable to the datastore\&. 
.SH "Typedef Documentation"
.PP 
.SS "typedef int \fBncds_id\fP"

.PP
Datastore ID\&. Each datastore gets its ID after initialisation (\fBncds_init()\fP)\&. Only initialised datastores can be used to access the configuration data\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBNC_DATASTORE\fP"

.PP
Enumeration of the supported types of datastores defined by NETCONF\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINC_DATASTORE_ERROR \fP\fP
error state of functions returning the datastore type 
.TP
\fB\fINC_DATASTORE_CONFIG \fP\fP
value describing that the datastore is set as config 
.TP
\fB\fINC_DATASTORE_URL \fP\fP
value describing that the datastore data should be given from the URL 
.TP
\fB\fINC_DATASTORE_RUNNING \fP\fP
base NETCONF's datastore containing the current device configuration 
.TP
\fB\fINC_DATASTORE_STARTUP \fP\fP
separated startup datastore as defined in Distinct Startup Capability 
.TP
\fB\fINC_DATASTORE_CANDIDATE \fP\fP
separated working datastore as defined in Candidate Configuration Capability 
.SS "enum \fBNCDS_TYPE\fP"

.PP
Datastore implementation types provided by libnetconf\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINCDS_TYPE_ERROR \fP\fP
virtual enum value for internal purposes 
.TP
\fB\fINCDS_TYPE_EMPTY \fP\fP
No real datastore\&. For read-only devices\&. 
.TP
\fB\fINCDS_TYPE_FILE \fP\fP
Datastores implemented as files 
.TP
\fB\fINCDS_TYPE_CUSTOM \fP\fP
User-defined datastore 
.SH "Function Documentation"
.PP 
.SS "int ncds_add_model (const char *path)"

.PP
Add an configuration data model to the internal list of models\&. Such model is used to resolve imports, includes and uses statements in base models\&. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP Path to the YIN format of the configuration data model\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "int ncds_add_models_path (const char *path)"

.PP
Specify a directory path to the location where the required (imported or included) data models can be found\&. This function can be called repeatedly to specify multiple locations\&. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP Directory path 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "\fBnc_reply\fP* ncds_apply_rpc2all (struct nc_session *session, const \fBnc_rpc\fP *rpc, \fBncds_id\fP *ids[])"

.PP
Perform the requested RPC operation on the all datastores controlled by the libnetconf (created by ncdsd_new() and \fBncds_init()\fP)\&. \fBThis function IS NOT thread safety\&.\fP
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session (a dummy session is acceptable) where the <rpc> came from\&. Capabilities checks are done according to this session\&. 
.br
\fIrpc\fP NETCONF <rpc> message specifying requested operation\&. 
.br
\fIids\fP Pointer to a static array containing list of datastore IDs where the RPC was successfully applied\&. The list is terminated by value a (ncds_id)(-1)\&. The list is rewritten by any following call to \fBncds_apply_rpc2all()\fP\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
NULL in case of a non-NC_RPC_DATASTORE_* operation type or invalid parameter session or rpc, else <rpc-reply> with <ok>, <data> or <rpc-error> according to the type and the result of the requested operation\&. When the requested operation is not applicable to any datastore (e\&.g\&. the namespace does not match none of the controlled datstores), NCDS_RPC_NOT_APPLICABLE is returned\&. 
.RE
.PP

.SS "void ncds_break_locks (const struct nc_session *session)"

.PP
Remove all the locks that the given session is holding\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP Session holding locks to remove 
.RE
.PP

.SS "int ncds_consolidate (void)"

.PP
Consolidate all internal structures of created data stores and all data models\&. This function especially solves all YANG's \fCuses\fP and \fCaugment\fP statements\&. 
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "int ncds_feature_disable (const char *module, const char *feature)"

.PP
Disable usage of the specified feature defined in the specified module By default, all features are disabled\&. 
.PP
\fBParameters:\fP
.RS 4
\fImodule\fP Name of the module where the feature is defined\&. Module must be accessible - added via \fBncds_add_model()\fP or present in a directory specified via \fBncds_add_models_path()\fP function\&. 
.br
\fIfeature\fP Name of the feature to be disabled\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "int ncds_feature_enable (const char *module, const char *feature)"

.PP
Enable usage of the specified feature defined in the specified module\&. By default, all features are disabled\&. 
.PP
\fBParameters:\fP
.RS 4
\fImodule\fP Name of the module where the feature is defined\&. Module must be accessible - added via \fBncds_add_model()\fP or present in a directory specified via \fBncds_add_models_path()\fP function\&. 
.br
\fIfeature\fP Name of the feature to be enabled\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "int ncds_feature_isenabled (const char *module, const char *feature)"

.PP
Check if the feature of the specified module is currently enabled or disabled\&. 
.PP
\fBReturns:\fP
.RS 4

.IP "\(bu" 2
negative value in case of error
.IP "\(bu" 2
0 if feature is disabled
.IP "\(bu" 2
1 if feature is enabled 
.PP
.RE
.PP

.SS "int ncds_features_disableall (const char *module)"

.PP
Disable usage of all features defined in the specified module\&. By default, all features are disabled\&. To disable only the specific feature(s), use \fBncds_feature_disable()\fP\&. 
.PP
\fBParameters:\fP
.RS 4
\fImodule\fP Name of the module where the features are defined\&. Module must be accessible - added via \fBncds_add_model()\fP or present in a directory specified via \fBncds_add_models_path()\fP function\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "int ncds_features_enableall (const char *module)"

.PP
Enable usage of all features defined in the specified module\&. By default, all features are disabled\&. To enable only the specific feature(s), use \fBncds_feature_enable()\fP\&. 
.PP
\fBParameters:\fP
.RS 4
\fImodule\fP Name of the module where the features are defined\&. Module must be accessible - added via \fBncds_add_model()\fP or present in a directory specified via \fBncds_add_models_path()\fP function\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "void ncds_free (struct ncds_ds *datastore)"

.PP
Close the specified datastore and free all the resources\&. Equivalent function to \fBncds_free2()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIdatastore\fP Datastore to be closed\&. 
.RE
.PP

.SS "void ncds_free2 (\fBncds_id\fPdatastore_id)"

.PP
Close specified datastore and free all the resources\&. Equivalent function to \fBncds_free()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIdatastore_id\fP ID of the datastore to be closed\&. 
.RE
.PP

.SS "char* ncds_get_model (\fBncds_id\fPid, intbase)"

.PP
Return a serialized XML containing the data model in the YIN format\&. 
.PP
\fBParameters:\fP
.RS 4
\fIid\fP ID of the datastore whose data model we want 
.br
\fIbase\fP Set 1 to get only base model without any modification\&. Use 0 value to get complete data model including augmentation, substituted uses statements and removed disabled features of the model\&. In this case, returned string contains modified YIN format - there are <augment> elements inside the model including information about its namespace and module name\&.
.RE
.PP
\fBReturns:\fP
.RS 4
String containing YIN model\&. Caller must free the memory after use\&. 
.RE
.PP

.SS "const char* ncds_get_model_path (\fBncds_id\fPid)"

.PP
Return path to the file containing the datastore datamodel\&. 
.PP
\fBParameters:\fP
.RS 4
\fIid\fP ID of the datastore whose data model we want
.RE
.PP
\fBReturns:\fP
.RS 4
String containing the path to the file containing the datastore datamodel\&. The caller must NOT free the memory\&. 
.RE
.PP

.SS "\fBncds_id\fP ncds_init (struct ncds_ds *datastore)"

.PP
Activate datastore structure for use\&. The datastore configuration is checked and if everything is correct, datastore gets its unique ID\&.
.PP
\fBParameters:\fP
.RS 4
\fIdatastore\fP Datastore to be initiated\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Positive integer with the datastore ID on success, negative value on error\&.
.IP "\(bu" 2
-1 Invalid datastore
.IP "\(bu" 2
-2 Type-specific initialization failed
.IP "\(bu" 2
-3 Unsupported datastore type
.IP "\(bu" 2
-4 Memory allocation problem 
.PP
.RE
.PP

.SS "int ncds_model_info (const char *path, char **name, char **version, char **ns, char **prefix, char ***rpcs, char ***notifs)"

.PP
Informational function to get basic information about configuration data model in the given file\&. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP Path to the *\&.yin file with the configuration data model in YIN format\&.
.RE
.PP
Caller is responsible to free returned strings and arrays of strings\&. If a caller is not interested in a specific return value, NULL pointer can be set as parameter and the value of such a parameter will not be returned\&.
.PP
\fBParameters:\fP
.RS 4
\fIname\fP Name of the data model 
.br
\fIversion\fP Version of the data model 
.br
\fIns\fP Namespace for the data model 
.br
\fIprefix\fP Prefix for the data model 
.br
\fIrpcs\fP Null terminated list of names of RPCs defined in the data model 
.br
\fInotifs\fP Null terminated list of names of Notifications defined in the data model 
.RE
.PP
\fBReturns:\fP
.RS 4
EXIT_SUCCESS or EXIT_FAILURE on error\&. 
.RE
.PP

.SS "struct ncds_ds* ncds_new (\fBNCDS_TYPE\fPtype, const char *model_path, char *(*)(const char *model, const char *running, struct nc_err **e)get_state)"

.PP
Create a new datastore structure of the specified implementation type\&. 
.PP
\fBParameters:\fP
.RS 4
\fItype\fP Datastore implementation type for the new datastore structure\&. 
.br
\fImodel_path\fP Base name of the configuration data model files\&. libnetconf expects model_path\&.yin as a data model, model_path\&.rng for grammar and data types validation, model_path\&.dsrl for default values validation and model_path\&.sch for semantic validation\&. 
.br
\fIget_state\fP Pointer to a callback function that returns a serialized XML document containing the state configuration data of the device\&. The parameters it receives are a serialized configuration data model in YIN format and the current content of the running datastore\&. If NULL is set, <get> operation is performed in the same way as <get-config>\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Prepared (not configured) datastore structure\&. To configure the structure, caller must use the parameter setters of the specific datastore implementation type\&. Then, the datastore can be initiated (\fBncds_init()\fP) and used to access the configuration data\&. 
.RE
.PP

.SS "struct ncds_ds* ncds_new2 (\fBNCDS_TYPE\fPtype, const char *model_path, xmlDocPtr(*)(const xmlDocPtr model, const xmlDocPtr running, struct nc_err **e)get_state)"

.PP
Create a new datastore structure of the specified implementation type with get_state function using libxml2\&. To make this function available, you have to include \fBlibnetconf_xml\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fItype\fP Datastore implementation type for the new datastore structure\&. 
.br
\fImodel_path\fP Base name of the configuration data model files\&. libnetconf expects model_path\&.yin as a data model, model_path\&.rng for grammar and data types validation, model_path\&.dsrl for default values validation and model_path\&.sch for semantic validation\&. 
.br
\fIget_state\fP Pointer to a callback function that returns a XML document containing the state data of the device\&. The parameters it receives are a configuration data model in YIN format and the current content of the running datastore\&. If NULL is set, <get> operation is performed in the same way as <get-config>\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Prepared (not configured) datastore structure\&. To configure the structure, caller must use the parameter setters of the specific datastore implementation type\&. Then, the datastore can be initiated (\fBncds_init()\fP) and used to access the configuration data\&. 
.RE
.PP

.SS "int ncds_rollback (\fBncds_id\fPid)"

.PP
Undo the last change performed on the specified datastore\&. 
.PP
\fBParameters:\fP
.RS 4
\fIid\fP ID of the datastore where the rollback will be performed\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error\&. 
.RE
.PP

.SS "int ncds_set_validation (struct ncds_ds *ds, intenable, const char *relaxng, const char *schematron)"

.PP
Set validators (or disable validation) on the specified datastore\&. 
.PP
\fBParameters:\fP
.RS 4
\fIds\fP Datastore structure to be configured\&. 
.br
\fIenable\fP 1 to enable validation on the datastore according to the following parameters, 0 to disable validation (following parameters will be ignored as well as automatically or previously set validators)\&. 
.br
\fIrelaxng\fP Path to the Relax NG schema for validation of the datastore content syntax\&. To generate it, use the lnctool(1) script\&. NULL if syntactic validation is not required\&. 
.br
\fIschematron\fP Path to the Schematron XSLT stylesheet for validation of the datastore content semantics\&. To generate it, use the lnctool(1) script\&. NULL if semantic validation is not required\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
EXIT_SUCCESS or EXIT_FAILURE 
.RE
.PP

.SS "int ncds_set_validation2 (struct ncds_ds *ds, intenable, const char *relaxng, const char *schematron, int(*)(const xmlDocPtr config, struct nc_err **err)valid_func)"

.PP
Set validators (or disable validation) on the specified datastore\&. To make this function available, you have to include \fBlibnetconf_xml\&.h\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIds\fP Datastore structure to be configured\&. 
.br
\fIenable\fP 1 to enable validation on the datastore according to the following parameters, 0 to disable validation (following parameters will be ignored as well as automatically or previously set validators)\&. 
.br
\fIrelaxng\fP Path to the Relax NG schema for validation of the datastore content syntax\&. To generate it, use the lnctool(1) script\&. NULL if syntactic validation not required\&. 
.br
\fIschematron\fP Path to the Schematron XSLT stylesheet for validation of the datastore content semantics\&. To generate it, use the lnctool(1) script\&. NULL if semantic validation not required\&. 
.br
\fIvalid_func\fP Pointer to a callback function that is used for additional validation of the configuration data in the datastore\&. It can perform any specific check for the datastore (e\&.g\&. check for presence of referred files)\&. If no such check is needed, parameter can be set to NULL\&. 
.br
 Validation callback function receives configuration data as a libxml2's xmlDocPtr\&. As a result it returns EXIT_SUCCESS if validation checks passed and EXIT_FAILURE when an error occurred\&. An error description may be returned via the \fCerr\fP parameter\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
EXIT_SUCCESS or EXIT_FAILURE 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libnetconf from the source code\&.
